package com.google.code.virtualhockey.vhx.shared.rpc;

import com.google.code.virtualhockey.vhx.shared.error.WebServerException;
import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * <p>
 * GWT/RPC remote service servlet which is used to route commands from the
 * client to the server.
 * </p>
 *
 * <p>
 * Please make sure to include a servlet mapping for a server side
 * implementation into your application's web.xml file! The servlet should
 * respond to any request directed at the path <code>command.rpc</code>.
 * </p>
 */
@RemoteServiceRelativePath( "command.rpc" )
public interface IRpcCommandService extends RemoteService
{
  /**
   * Handles the given command and returns a response or throws an exception in
   * case of handling failures.
   *
   * @param strSecurityToken some security token which is checked by the server
   *          to avoid CSRF attacks
   * @param command the command to be executed remotely
   * @return the command response
   * @throws WebServerException if there is a server side processing failure
   */
  public IResponse handle( String strSecurityToken, ICommand<?> command ) throws WebServerException;
}
